                          Generic STOS Fixer v1.3
                          =======================
 
  
 Contents:
 ---------
 
     + Introduction.
     + Usage instructions.
        - drag & drop.
        - command line.
        - GEM based.
     + Limitiations.
     + Falcon Compatibility.
     + Known Bugs/problems.
     + Legal stuff.
     + Credits.
     + Contact info.
     + Advertisements.
 
 
 
 
 Introduction:
 -------------
 
 When STOS was  written,  it was  decided that  to improve  the speed  of  some
 commands  the addresses  of certain  routines in  the Operating  System  could
 be stored  in a  table at the beginning of the program to  prevent them having
 to be  looked up each  time it  is run.  However,  as these  addresses  change
 with  every  new  release  of  the  Operating  System STOS  had to be updated.
 While  Mandarin  still supported  STOS this  was OK,  as they  simply released
 a new  version  with  the  updated  table,  along with any bug fixes. However,
 as  Mandarin  no  longer  support  STOS  there have  been no official releases
 containing  new  tables  for  any version  of TOS  greater  than  TOS 1.62. To
 get  around this  problem,  any compiled  STOS program  can be  'fixed'  which
 simply  means  replacing the  table with a  suitable table for  the OS version
 - this is essentially what Mandarin would have done.
 
 At this  time,  there are  two STOS fixers available (with numerous versions),
 the latest  version of each  is called  STOS Fix 3. However,  neither of these
 is perfect.  One, by  Robert  Quezada,  only fixes  the STOS  program for  the
 CURRENT version of  TOS, thus  making it  necessary for  the end  user of  the
 program, not the author to fix the program - this seems rather unprofessional.
 The  other  (so  I am  told - I  don't have  it), from  Goodmans PDL, is  only
 available  from Goodmans, and  is not available via FTP on the internet. Also,
 it places an advert for Goodmans PDL on any STOS program fixed with it -again,
 not very professional.
 
 So, the solution is the Generic STOS Fixer. This fixes a  STOS program for any
 8  versions of TOS  (unfortunately,  at this time  there are 15  versions, not
 including  MagiC).  Which  versions  are used is determined by the DEFxxxx.DAT
 files in  the same  directory as  GENFIX.PRG,  where xxxx  is the  TOS version
 number, and also the settings if you have used the GEM interface.
 
 Supplied with this program are DEFxxxx.DAT files for all existing TOS versions
 from TOS 1.0 through to 4.92 except TOS 3.05 (if anyone has this version,  and
 has a joystick,  please get in touch - I would  like to obtain this versions.)
 Which files are omitted is up to the person fixing the program.
 
 It is no longer  necessary for authors to fix their programs  with this or any
 other fixer before release - they should simply install my new patched loaders
 for the interpreter and  compiler (BASIC207.TOS and COMP_207.PRG)  before they
 compile  their software.  Generic STOS Fixer is now only needed  if the author
 did not do this before releasing their software.


 Usage instructions:
 -------------------
 
 This program will work in a number of ways -
 
 1) Drag a file to the program  icon (TOS 2.06 or  greater required). This will
    start up the fixer, which will attempt  to fix the program. The DEFxxxx.DAT
    files will be taken from the CURRENT directory - ie. the top window if this
    option is set (or the applications directory, otherwise).
 
    This does  NOT start a  GEM based version,  and may well corrupt the screen
    if running under MultiTOS. (Hmmm.... I'll have to check this...)
 
 2) Enter the filename on the command line.This is very similar to the previous
    method. Once again,  this is not  a GEM based  method, and is  suitable for
    running from a command shell (eg BASH/KSH/CSH under MiNT).
 
 3) Double  click on  the program icon. This will  start up  the program  as it
    would any other.  A GEM based  shell is provided,  which eases  use of  the
    program.  Note that  it will be  difficult (if not  impossible) to use this
    method in a resolution with < 640 pixels horizontally.
 
    To actually perform the fixing process, select the 'Fix' button, and select
    the program to fix with the file selector. Hopefully, it should now fix the
    program.  Once the  fix has  been completed, there should  be a copy of the
    program with the file extension  renamed to .123 and  the original  program
    should now work with the specified OS versions. (see notes on compatibility
    below...)
 
    However, before fixing it may be necessary to select which  versions of TOS
    are to be fixed for. To do this, select 'OS Versions'. This will bring up a
    second dialogue. 
 
    In the scrollable list on the left are  shown all of the  DEFxxxx.DAT files
    found. Any filename shown in white on black is selected,  and will  be used
    when  fixing - to [de]select  a file, click on  it with the mouse.  Up to 8
    files may be selected at any one time.
 
    The 'default' file is the  one which STOS will use if the  required file is
    not found. To set this, line the file which you wish to be the default with
    this line, and press the sideways arrow.
 
    'Cancel' will  restore the settings to the previous  values, and  'Ok' will
    accept any changes made. It should  be noted that any  changes will  NOT be
    saved, and so may need to be done every session. Also note that all changes
    except  for the  'default'  file are  made  imediately,  so fixing  without
    closing this dialogue will use the new settings except for 'default'  which
    will be as set previously.
 
    The  default settings for this should be OK for general  purpose - if there
    are more than 8 DAT files (14 are distributed  with this release),  then as
    many TOS versions excluding TOS 1.1 and 4.92 are  selected as is  possible.
    These two are omitted as they are very rare. The  default file  is selected
    to either be the first OS version found, or if there are any 4.0x versions,
    this is chosen. This is because  the tables for 4.01, 4.02 and 4.04 are all
    identical - thus, it is a waste of space to include all 3. With the default
    settings  and  files, TOS 1.0, 1.02, 1.04, 1.06, 1.62, 2.05, 2.06  and 4.01
    should be selected.  As 4.01 is the  default, 4.02 and 4.04 should  also be
    operative.

 After fixing has taken place (if successful) there will be two files - one the
 fixed program,  and also a  second (<FILENAME>.123) which will be the original
 unfixed program.  This is so  that should anything  go wrong, you still have a
 backup.
 
 You CAN use  this program to fix the BASIC206.PRG  program which  launches the
 STOS  editor - simply  fix in exactly  the same way as any other STOS program.
 Also,  if you fix  the COMP207.PRG file in  the compiler folder,  all programs
 compiled will be fixed for this set of TOS versions.

 
 Limitations.
 ------------
 
 This program will not  necessarily fix a program  which has already been fixed
 by either this fixer, or either of the other two fixers available - always fix
 straight after compilation to solve problems of this kind.  (This is dependent
 on the 'default' file selected previously.)
 
 Also, programs which have been packed will not be fixable - use NewDepack from
 Sinister Developments to decompress the program. 
 
 Programs which use extensions may still not work after being fixed - check the
 Falcon compatibility section below for more details.
 
 I cannot guarantee that all programs can be fixed. However, if after fixing it
 successfully  works on your machine, it probably works  under all TOS versions
 that you have specified. If STOS Fix 3 by R.Quezada does not fix a program, it
 is highly unlikely that this program will have any more luck.
 
 
 
 
 Falcon Compatibility.
 ---------------------
 
 The Falcon has a number of major changes  from the ST -  this causes  programs
 which have been written without considering  these changes  likely to  cause a
 crash.  However,  it is  possible to  write a  program in STOS  that will work
 without problems on the Falcon.
 
 The things to consider with regard to the Falcon are:
 
 1) Dont pack your program with the 'Atomic Packer' as this crashes the Falcon.
    - use  PACK ICE  instead.  (Interesting note:  in Top Notch's  Missing Link
    Extension documentation they say that the Falcon is very compatible - guess
    which packer they used to pack the install program!)
  
 2) Rename your program from PRG to TOS - This will cause the graphics commands
    to work better. Always do this as there is no advantage to being a PRG file
    (unless  its a  GEM  program, which  is currently  impossible  for  a  STOS
    program). 
 
 3) Run the  Falcon with a clean  setup - hold down control while booting. This
    will start the Falcon in ST-Low  resolution, with  no desk accessories/auto
    boot programs but with the hard-drive active. Holding down 'Alternate' will
    also disable the hard-drive.
 
 4) When using extensions, try and use Falcon tested commands -  some extension
    authors have done some nasty things which  crash the Falcon. The  following
    extensions have been tested on the Falcon, and work without problems:
 
      Maestro, Control, Extra, Ninja Tracker, Falcon (obviously), Compact,
      Blitter and Compiler.
 
    The Missing Link works, although a couple of commands do not  - namely  the
    music/sample  playing  routines.  Also,  the 'P STOP'  command  causes  the
    keyboard  handler to go a  little mad  (like the key repeat bug...).  Other
    commands  (such as 'rasters') also do not  appear to work 100%. I will have
    to test this fully...
 
    The STE Extension, and any other STE extension probably work on the Falcon,
    although there are slight differences in the way hardware  scrolling works,
    and also the lowest frequency provided on the STE DMA hardware is not valid
    so will not generate any sound. (This is the reason Heartland does  not get
    the STE sound on Falcons).
 
    The  following extensions  do  NOT  work on  the Falcon,  and so  should be
    avoided.
 
      STOS Tracker (the one that uses .ABK files).
 
 If at  all  possible you  should try  and get  your STOS programs  tested on a
 Falcon before releasing it. However, if you cannot it is still worth doing the
 above so that you have a higher chance of it working correctly.

 Dont forget that your program will run faster on a Falcon,  so just because it
 works doesn't mean that   it is playable.  This is a problem  which I  have no
 answer to. All I can say is if speed makes a difference,  it should definately
 be playtested on a Falcon.
 
 
 Known bugs/problems:
 --------------------
 
 The entire program is  loaded into memory - thus  making it  difficult to  fix
 BIG programs on a 520 (or maybe  even 1040). [Thats fine with me  - I have 8Mb
 in my Falcon. :-)] 
 
 As mentioned above, you cannot fix a program twice.  This is due to the method
 which is used to identify a STOS program - it will patch the wrong part of the
 file of a program already fixed. This may be changed in later versions  (but I
 think this is unlikely).
 
 Under  MagiC GenFIX will  not  get a correct  name under  the  desk-menu  like
 MultiTOS -  this is because I am  following Atari's documentation and checking
 for AES 4.0 for this functionality - not AES 3.99. As I do not have MagiC (and
 do not intend to buy it)  I refuse to  gaurantee that  this program  will work 
 under  MagiC,  as  the   programmers  are  not  following  Atari's  documented 
 functionality (to quote Andreas Kroeme in a recent usenet discussion -  "Atari 
 didn't always do things the best way". So? They set the standard for the OS on
 *Atari* computers, so if you are writing a  *compatible* OS  then  FOLLOW  THE
 STANDARD. <rant off>)
 
 
 Legal stuff:
 ------------
 
 This program is released as FREEWARE. As such, this program may be distributed
 in any form (PD libaries, electronic  file transfer, coverdisks etc.)  so long
 as none of the files enclosed are modified, or omitted. 
 
 Also, there is no waranty that this program will  work - explicit or  implied.
 This program directly modifies  program files - thus  there is a potential for
 programs to  be damaged - you  fix  programs  AT  YOUR  OWN  RISK.  Always run
 this program on a backup.
 
 Although this program is Freeware,  any donations  are welcome,  and would  be
 gratefully received. :-) 
 


 Credits:
 --------
 
 Original fixer code:    Les Greenhalgh
           (in STOS)
 
 C implementation:       Anthony Jacques
 
 DEFxxxx.DAT files
        created by:      STOS Fix 3, by Robert Quezada
        
 Thanks to everyone who sent me the DEFxxxx.DAT files so that I  could build up
 a complete collection... 
 
 
 
 Contact info:
 -------------
 
 Anthony Jacques:
 
       70 West Avenue,
       Oldfield Park
       Bath
       Somerset
       BA2 3QD 
       England
 
   term-time 96/97:  
       Sycamore Flat 38
       Oak House
       Whitworth Lane
       Manchester
       England

   email: jacquesa@cs.man.ac.uk
   WWW:   http://www.cs.man.ac.uk/~jacquesa/
   IRC:   AnthonyJ

 Les Greenhalgh:
       24 Park Avenue
       Rudloe Manor
       Corsham
       Wiltshire
       SN13 0JT
       England
 
 Robert Quezada:
 
    I have no contact address for Robert - the email address in his
    STOS Fix 3 documentation is no longer valid.


 Recent History:
 ---------------
 
 Version 1.4:

 Added DEF files for 3.01 and 3.06 after a little rant on comp.sys.atari.programmer. :)
 Updated doc files to reflect my work on the STOS loader.

 Version 1.3:
 
 Fixed the various GEM bugs.
 Speeded up file read/write functions.
 Added non-modal dialogues.
 Re-organised code - more elegent, and much smaller! (binary size dropped by
 10k - thats about 20%)
 
 Version 1.2:
 
 Improved the documentation in response to user questions.
 Removed the STUPID debugging aid that I left in the previous release. (the
 'error' message. Why did knowone tell me about this BEFORE I sent it to STF?)

 Version 1.1:
 
 The version released on ST Format coverdisk 83.
 Full functionality, just a little slow with a 'fake' error message and a few
 redrawing bugs on AES versions < 3.30 (Falcon).
 

 Well, thats about all you need to know....

 Anthony Jacques, 24/6/96


 8<- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


 Advertisements....


 Falcon Missing Link - will be shareware (10-15 pounds?).
 
 Not yet available, but in development. This program will revolutionise  Falcon
 games programming in the  same way as The  Missing Link did  for the ST.  This
 extension will provide the same functionality as TML,  but allow access to the
 Falcon's superior hardware.
 
 If you are interested in this, please contact me. No response = no development.
 
 
 
 
 STOS Falcon Extension v1.3 - shareware (5 pounds registration)
 
   +  true colour sprite routines - including NEW scale and fragment
      effects. 
   +  DSP playback of 4-32 channel modules at 50khz 16-bit stereo.
   +  full access to the sound system (including dsp processing).
   +  4 to 65536 colour graphics routines.
   +  Playback of FLI and FLC animations in truecolour.

 Note that this is shareware. Despite being featured in ST Format, less than 10
 people registered this program.  I am tempted not to release further shareware
 products on the Atari.  (I already have a PC,  and have started programming on
 this, so if you want me to release more Atari software, SHOW ME that it is not
 a waste of time...)

 For more information, contact:
 
 Anthony Jacques, 70 West Avenue, Oldfield Park, Bath. BA2 3QD
 http://www.cs.man.ac.uk/~jacquesa/  or  jacquesa@cs.man.ac.uk
 
 
 
 STOS Mailing list.
 
 Are you a STOS user who is online? Well, if you have internet access, then you
 can join the STOS mailing list and take part in STOS discussions/ask questions
 to some  of the  best STOS  programmers  around - Martin Cubitt  author of the
 Extra Extension, Tony Greenwood of STOSSER Software and Anthony Jacques author
 of the STOS Falcon Extension, as well as many other STOS programmers.

 For more information, email: jacquesa@cs.man.ac.uk
 
 To subscribe send a mail to: stos-request@man.ac.uk with the word subscribe in
 the body of the email.
 
 
 
 STOS FTP sites.
 
 The biggest FTP site on the  InterNET for STOS  software is ftp.uni-kl.de STOS
 stuff can be found  in the pub/Atari/programming/STOS/ directory.  If you  are
 using a WWW-browser such as Netscape, then the address is:-
 ftp://ftp.uni-kl.de/pub/Atari/programming/STOS/
 
 Also worth a look  is the funet archive in Finland (I believe the address is:
                                              ftp.funet.fi but I'm not certain)
 
 
 
 
 Bad Mood.
 
 This is an  internet project to create a Falcon  (and perhaps TT/Eagle/Medusa)
 version of Doom. It is looking less likely all the time that this will ever be
 finished. If you are interested in helping out with the coding, PLEASE contact
 us...
 
 For more information, visit: http://rand.thn.htu.se/~johan/bad_mood.html or to
 join the  Bad Mood mailing list, email  bad_mood-request@rand.thn.htu.se  with
 the word subscribe in the subject line.



 
 GEM-DEU.
 
 This is my (main) contribution to Bad Mood - a complete GEM based level editor
 for the Doom series. This is fast becoming more than just a level editor (with
 graphics and sound import/export functions etc.) and  supports all  the latest
 GEM functionality  (non-modal dialogues,  AES 4.1 toolbars,  context sensative
 ST-Guide help, MultiTOS drag'n'drop messages etc.)
 
 The current version is 0.7d,  but this is changing on an  almost weekly basis.
 For the latest info (and download source/executables) check my WWW pages:
     http://www.cs.man.ac.uk/~jacquesa/gem-deu.html
 
 
 8<- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 